openUBMC yocto_soc OEE源码构建工具链 - 详细设计说明书

所属SIG组:CICD
落入版本:26.09
设计人员:马思雨
日期:2026.7.16

Copyright © 2026 openUBMC Community

您对"本文档"的复制,使用,修改及分发受木兰宽松许可证, 第2版协议(以下简称"MulanPSL2")的约束。 为了方便用户理解,您可以通过访问https://license.coscl.org.cn/MulanPSL2了解MulanPSL2的概要 (但不是替代)。 MulanPSL2的完整协议内容您可以访问如下网址获取:https://license.coscl.org.cn/MulanPSL2

改版记录

日期修订版本修订描述作者审核
2026/07/160.0.1初始版本masiyu

List of abbreviations 缩略语清单

Abbreviations 缩略语Full spelling 英文全名Chinese explanation 中文解释
OEEOpenEuler EmbeddedOpenEuler嵌入式版本
BMCBaseboard Management Controller基板管理控制器
BSPBoard Support Package板级支持包
YoctoYocto Project开源嵌入式构建系统
SDKSoftware Development Kit软件开发工具包
AST2600ASPEED Technology 2600ASPEED AST2600芯片
SPLSecondary Program Loader二级程序加载器
MMCMulti Media Card多媒体卡(含eMMC)
MTDMemory Technology Device内存技术设备(SPI Flash)

[TOC]

1.功能分析

1.1 功能背景

需求来源

在openUBMC社区中,OEE(OpenEuler Embedded)产品的BMC固件需要基于源码构建工具链并发布到社区,原有流程存在以下问题:

  1. OEE产品无源码构建能力:OEE BMC需要基于openEuler Embedded 24.03 LTS的Yocto构建系统,但缺乏标准化的BSP层和构建脚本
  2. 工具链不可重复构建:ARM交叉工具链仅以预编译二进制形式提供,社区开发者无法复现和验证
  3. 社区流水线无构建入口:CI/CD系统缺乏从源码到SDK产物的完整构建流水线脚本

用户价值

通过创建yocto_soc仓库并提供setup_oee.sh一键构建脚本,为openUBMC社区带来以下价值:

  1. OEE产品源码可构建:基于Yocto oebuild工具链,从源码完整构建BMC固件、U-Boot、内核和SDK
  2. 社区可复现:所有构建配置版本化管理,开发者可验证和复现任意版本的构建产物
  3. 流水线自动化:setup_oee.sh作为社区流水线的构建入口,实现从源码拉取到SDK产物的全自动化

损失描述

若无此功能,将导致:

  • OEE BMC无法在社区实现源码级构建和发布
  • 社区CI/CD无法集成OEE产品的构建验证
  • 开发者需要自行搭建完整的Yocto环境和BSP层,门槛较高

1.2 功能描述

整体功能

  1. 新建yocto_soc仓,提供基于openEuler Embedded 24.03 LTS的ASPEED AST2600 BMC BSP层
  2. 提供双层Yocto Layer设计(meta-aspeed SoC层 + meta-ubmc板级层),支持UMMC(eMMC)和UMTD(SPI Flash)两种平台变体
  3. 提供setup_oee.sh一键构建脚本,覆盖从环境准备、oebuild初始化、源码拉取、平台配置、bitbake编译到SDK打包的全流程
  4. 产物为oee_sdk.zip,包含U-Boot、内核initramfs、根文件系统、ARM交叉工具链

实现方式

  • 新建meta-aspeed/层:SoC级BSP,提供AST2600的机器配置、tuning、U-Boot/内核provider声明
  • 新建meta-ubmc/层:板级BSP,提供UMMC(eMMC)和UMTD(SPI Flash)单板配置、U-Boot env、initramfs、内核补丁
  • 新建.oebuild/目录:提供oebuild平台定义和manifest版本锁定
  • 新建setup_oee.sh:一键编译与SDK打包脚本,社区流水线直接调用

1.3 功能场景

业务场景

场景编号场景名称描述使用对象
SC-01社区流水线构建CI/CD系统调用setup_oee.sh完成从源码到SDK的完整构建CI/CD系统
SC-02开发者本地构建开发者在本地环境使用setup_oee.sh构建调试开发者
SC-03单板平台切换通过-board参数切换UMMC/UMTD/AST2600 EVB平台开发者
SC-04BSP层定制基于meta-aspeed和meta-ubmc双层架构定制新单板开发者

使用对象

对象技能要求使用频度
CI/CD系统了解shell/python编程,流水线维护每次版本构建
开发者基础命令行操作与Yocto构建理解开发调试时
版本管理员了解oebuild和manifest操作版本发布时

使用时间

  • 构建时自动执行:作为社区流水线的一环,每次版本发布触发执行
  • 开发按需执行:开发者本地调试时手动触发

1.4 功能列表

功能编号功能标题功能描述
F-01SoC BSP层(meta-aspeed)提供AST2600芯片级机器配置和通用include
F-02板级BSP层(meta-ubmc)提供UMMC/UMTD单板配置、U-Boot、initramfs、内核补丁
F-03oebuild平台定义提供oebuild平台YAML和manifest.yaml版本锁定
F-04一键构建脚本(setup_oee.sh)从环境准备到SDK打包的全自动构建入口
F-05SDK打包编译后将U-Boot、根文件系统、initramfs、工具链打包为oee_sdk.zip

2.功能设计

2.1 总体方案分析

2.1.1 方案详细设计

2.1.1.1 方案概述

整体实现

本方案通过新建yocto_soc仓,提供基于openEuler Embedded 24.03 LTS的双层Yocto BSP架构和自动化构建脚本,支撑OEE源码构建工具链并发布到社区:

关键点

关键点描述技术实现
双层BSP架构SoC层与板级层分离设计meta-aspeed + meta-ubmc
平台变体同时支持eMMC和SPI Flash启动UMMC / UMTD
一键构建环境准备到SDK打包全自动化setup_oee.sh
oebuild集成基于openEuler Embedded标准构建工具.oebuild/平台定义 + manifest
SDK产物标准化统一的SDK打包格式oee_sdk.zip + 各子目录

实现策略

  1. 新建meta-aspeed层,提供aspeed.inc/ast2600.inc通用include和ast2600.conf机器配置
  2. 新建meta-ubmc层,提供ummc.conf/umtd.conf单板配置,通过require继承ast2600.conf
  3. 新建.oebuild/目录,定义平台YAML(ummc/umtd/ast2600)和manifest版本锁定
  4. 编写setup_oee.sh,覆盖用户创建、依赖安装、Docker配置、oebuild初始化、源码拉取、bitbake编译、SDK打包

2.1.1.2 开发视图

代码结构

text
yocto_soc/
├── meta-aspeed/                            # SoC BSP层 (collection: openubmc-aspeed)
│   └── conf/
│       ├── layer.conf                      # layer集合声明
│       └── machine/
│           ├── ast2600.conf                # AST2600 EVB参考机器
│           └── include/
│               ├── aspeed.inc              # Aspeed家族通用配置
│               └── ast2600.inc             # AST2600专用配置

├── meta-ubmc/                              # 板级BSP层 (collection: yocto_soc, priority 60)
│   ├── conf/
│   │   ├── layer.conf                      # layer集合声明,含BBFILES_DYNAMIC
│   │   └── machine/
│   │       ├── ummc.conf                   # UMMC单板 (eMMC启动,A/B双根文件系统)
│   │       └── umtd.conf                   # UMTD单板 (SPI flash/MTD启动)
│   ├── recipes-bsp/u-boot/                 # U-Boot补丁与单板差异化配置
│   ├── recipes-core/                       # 镜像、包组、busybox、systemd、udev
│   │   ├── images/                         # openeuler-image-obmc.bbappend
│   │   ├── packagegroups/                  # packagegroup-ubmc-base.bb
│   │   ├── busybox/                        # busybox配置碎片
│   │   ├── systemd/                        # systemd配置
│   │   └── udev/                           # udev规则
│   ├── recipes-kernel/linux/               # 内核补丁 (PECI、GNR、MTD、netfilter)
│   ├── recipes-ubmc/initrdscripts/         # initramfs脚本 (mmc vs mtd)
│   ├── recipes-devtools/m4/               # m4工具链兼容适配
│   └── dynamic-layers/                     # 对其他层的条件式bbappend

├── .oebuild/                               # oebuild平台定义
│   ├── manifest.yaml                       # 远程仓库版本锁定
│   └── platform/
│       ├── ummc.yaml                       # 平台定义: UMMC
│       ├── umtd.yaml                       # 平台定义: UMTD
│       └── ast2600.yaml                    # 平台定义: AST2600 EVB

├── setup_oee.sh                            # 一键编译与SDK打包脚本
└── README.md                               # 仓库说明与使用指南

构建产物目录结构

text
build/<单板>/sdk/
├── oee_sdk/
│   ├── u-boot-spl.bin                      # SPL二级引导程序
│   ├── u-boot.bin                          # U-Boot主体
│   ├── u-boot-env.bin                      # U-Boot环境变量
│   ├── u-boot-env.img                      # env镜像(2M,双副本)
│   ├── fitImage-core-image-tiny-initramfs-<单板>.img  # initramfs启动镜像
│   ├── oee_rootfs.tar.gz                   # 根文件系统
│   └── fitImage.img                        # initramfs ext4格式镜像
├── oee_compiler/
│   └── openeuler-x86_64-obmc-armv7a-ast2600-toolchain-24.03-LTS.sh  # ARM交叉工具链
├── lua-format/                             # Lua格式化工具(可选)
├── hpm_tools/                              # HPM打包工具(可选)
└── oee_sdk_<时间戳>.zip                    # 最终打包产物

2.1.1.3 运行视图

构建流程时序

text
┌──────────────┐     ┌─────────────────┐     ┌──────────────────┐
│ setup_oee.sh │────▶│ 系统环境准备    │────▶│ 创建编译用户      │
│  (入口脚本)   │     │ apt+git+docker  │     │ useradd + sudo   │
└──────────────┘     └─────────────────┘     └──────────────────┘

                    ┌────────────────────────────────┴───────────────┐
                    │  su - 编译用户                                 │
                    │  ┌───────────────────────────────────────────┐ │
                    │  │ oebuild init 工作区 -b openEuler-24.03-LTS│ │
                    │  │ oebuild update                            │ │
                    │  │ git clone yocto_soc                       │ │
                    │  │ 复制 platform/* -> yocto-meta-openeuler   │ │
                    │  │ 合并 manifest.yaml                        │ │
                    │  │ oebuild generate -p <单板>                │ │
                    │  └───────────────────────────────────────────┘ │
                    └────────────────────────────────────────────────┘

               ┌────────────────────┴────────────────────┐
               │  bitbake 编译阶段                        │
               │  ┌─────────────────────────────────┐    │
               │  │ [1/3] openeuler-image-obmc      │    │
               │  │ [2/3] u-boot-aspeed-sdk         │    │
               │  │ [3/3] populate_sdk              │    │
               │  └─────────────────────────────────┘    │
               └─────────────────────────────────────────┘

               ┌────────────────────┴────────────────────┐
               │  SDK打包阶段                             │
               │  ┌─────────────────────────────────┐    │
               │  │ 复制工具链 .sh -> oee_compiler/  │    │
               │  │ 复制U-Boot产物 -> oee_sdk/       │    │
               │  │ 制作 u-boot-env.img              │    │
               │  │ 制作 fitImage.img                │    │
               │  │ 打包为 oee_sdk_<时间戳>.zip      │    │
               │  └─────────────────────────────────┘    │
               └─────────────────────────────────────────┘

平台配置结构

yaml
# .oebuild/platform/<名称>.yaml
type: platform
machine: ummc/umtd               # 对应meta-ubmc/conf/machine/<机器名>.conf
toolchain_type: EXTERNAL_TOOLCHAIN:arm
repos:
  - yocto_soc                  # 本仓库
  - metaBMC                    # MetaBMC基础层
layers:
  - yocto_soc/meta-aspeed      # SoC BSP层
  - yocto_soc/meta-ubmc        # 板级BSP层
  - metaBMC/meta-openeuler     # openEuler嵌入式元层
  - metaBMC/meta-aspeed        # MetaBMC Aspeed层
local_conf: |
  OPENEULER_PREBUILT_TOOLS_ENABLE = "no"   # 使用源码编译工具链
  DISTRO_FEATURES:append = " kernel6"       # 启用6.6内核
  INIT_MANAGER = "systemd"                  # systemd初始化
  ROOT_HOME = "/home/root"
  PREFERRED_VERSION_linux-openeuler = "6.6%"

构建产物组织

text
UMMC平台:
  u-boot-spl.bin      <- ast2600_openbmc_spl_emmc_defconfig
  u-boot.bin           <- eMMC启动U-Boot
  u-boot-env.bin       <- 1MB env (存放于mmcblk0p1)
  initramfs            <- ubmc-mmc-init.sh (MMC设备等待+GPT修复+A/B切换)
  根文件系统            <- ext4双分区 (rofs-a/rofs-b)

UMTD平台:
  u-boot-spl.bin      <- ast2600_openbmc_spl_defconfig
  u-boot.bin           <- SPI Flash启动U-Boot
  u-boot-env.bin       <- 128KB env (存放于MTD分区)
  initramfs            <- ubmc-mtd-init.sh (MTD分区查找+TFTP/HTTP更新)
  根文件系统            <- Squashfs只读 + JFFS2读写overlay

2.1.2 内部依赖分析

依赖项依赖组件依赖内容完成状态
meta-aspeedmeta-ubmc layer.confLAYERDEPENDS = "openubmc-aspeed openeuler"已完成
meta-ubmcmeta-aspeed ast2600.confUMMC/UMTD通过require继承已完成
平台YAMLyocto_soc仓库自身platform/定义机器、层、local_conf已完成

2.1.3 外部依赖分析

外部依赖类型版本要求用途
oebuildPython工具最新openEuler Embedded构建工具
MetaBMC远程仓库afbfd4fb (锁定)提供meta-openeuler/meta-aspeed基础层
Docker容器引擎latest构建隔离环境
Python 3运行环境>= 3.6oebuild运行依赖
git版本管理-源码拉取
openEuler Embedded构建系统24.03 LTSoebuild init基版本

2.1.4 北向接口分析

本功能为构建系统基础设施,不对外暴露北向接口。社区流水线通过调用setup_oee.sh触发构建。

2.1.5 兼容性分析

平台兼容性

平台类型是否支持启动存储说明
UMMC支持eMMC主推平台,A/B双根文件系统
UMTD支持SPI FlashSquashfs + JFFS2 overlay
AST2600 EVB支持SPI Flash参考板,使用MetaBMC原层

影响分析

  • yocto_soc仓为新建仓库,不涉及对现有组件的兼容性问题
  • 通过MACHINEOVERRIDES隔离各单板配置,互不影响
  • 平台YAML中的local_conf关闭了OPENEULER_PREBUILT_TOOLS_ENABLE,确保使用源码编译工具链

2.1.6 定制化接口分析

setup_oee.sh参数默认值

参数默认值说明
-user / TARGET_USERuser编译用户名
-pwd / TARGET_PASSuser编译用户密码
-init / INIT_NAMEoee_workspaceoebuild工作区名称
-board / PRODUCT_NAMEummc目标单板名(ummc/umtd/ast2600)

平台YAML可定制字段

配置项默认值说明
machineummc/umtd/ast2600目标机器类型
local_conf见平台YAML可通过local_conf注入自定义BitBake配置
reposyocto_soc + metaBMC可扩展其他依赖仓库

2.1.7 导入导出分析

不涉及配置导入导出。

2.1.8 传感器分析

不涉及传感器新增。

2.1.9 精准告警事件分析

不涉及事件新增。

2.1.10 系统锁定分析

不涉及系统锁定。

2.1.11 用例场景分析

用例编号用例名称前置条件操作步骤预期结果
UC-01社区流水线UMMC构建宿主机已安装Docker1. sudo ./setup_oee.shUMMC平台完整构建,oee_sdk.zip生成
UC-02UMTD平台构建宿主机已安装Docker1. sudo ./setup_oee.sh -board umtdUMTD平台完整构建,产物为SPI Flash版
UC-03AST2600 EVB构建宿主机已安装Docker1. sudo ./setup_oee.sh -board ast2600AST2600 EVB完整构建
UC-04自定义用户/工作区宿主机已安装Docker1. sudo ./setup_oee.sh -user myuser -pwd mypass -init myws以指定用户和工作区名完成构建
UC-05环境变量传参Docker环境就绪1. sudo env PRODUCT_NAME=umtd ./setup_oee.sh正常构建UMTD平台
UC-06SDK产物上传流水线构建完成1. 流水线获取oee_sdk.zip自动上传到repo仓对应位置

2.2 非功能质量属性设计

2.2.1 扩展性分析

  1. 可扩展单板:在meta-ubmc/conf/machine/新增.conf文件,继承ast2600.conf即可
  2. 可扩展平台定义:在.oebuild/platform/新增YAML文件,定义新平台的层组合
  3. 可扩展U-Boot变体:在recipes-bsp/u-boot/files/添加新板cfg和env文件,通过MACHINEOVERRIDES选择
  4. 可扩展内核补丁:在recipes-kernel/linux/linux-openeuler.bbappend中添加新补丁

2.2.2 重用性分析

  1. meta-aspeed层可作为公共SoC BSP,被多个板级层复用
  2. setup_oee.sh的框架逻辑(用户创建、依赖安装、oebuild初始化)可被其他类似项目复用
  3. 包组packagegroup-ubmc-base.bb集中管理通用依赖,所有单板共享

2.2.3 可测试性分析

  1. 单板维度验证:对ummc/umtd/ast2600三种平台分别验证构建完整性
  2. 产物验证:检查oee_sdk.zip中各文件(u-boot-spl.bin、u-boot.bin、fitImage、rootfs.tar.gz、工具链.sh)是否存在
  3. 增量构建验证:重复执行构建验证sstate缓存命中

2.2.4 文档资料分析

文档资料类型是否涉及说明
用户手册README.md提供构建指引和新板适配指南
开发指南README.md提供镜像定制、内核驱动、U-Boot修改等进阶操作
API文档无对外API

2.2.5 资源使用分析

不涉及资源使用变更(构建在Docker容器中执行,资源由CI/CD系统管理)。

2.2.6 可靠性分析

  1. 构建原子性:oebuild工作区在构建失败时不清除,保留现场供排查
  2. 产物完整性校验:SDK打包阶段逐一检查各产物文件是否存在
  3. 脚本幂等性:setup_oee.sh支持重复执行,用户已存在时仅更新密码和sudo权限
  4. 日志记录:构建日志写入/home/<用户>/tmp/目录,便于追溯

2.2.7 安全性分析

  1. 构建隔离:构建在Docker容器中进行,不影响宿主机环境
  2. 用户隔离:创建独立编译用户,通过sudoers授权Docker相关命令。需注意docker组成员拥有宿主机root等效权限(可挂载任意目录、运行特权容器、逃逸至宿主机),因此编译用户的实际安全边界等同root。在生产环境CI/CD中建议采用rootless Docker或podman替代方案以实现真正的用户隔离;当前设计适用于受控的开发/测试环境,默认密码(user)仅用于本地调试,生产环境必须强制修改
  3. 版本锁定:manifest.yaml锁定MetaBMC和yocto_soc的版本,防止供应链篡改

3.功能实现

3.1 yocto_soc OEE源码构建工具链功能实现

3.1.1 功能实现设计

meta-aspeed层

aspeed.inc提供Aspeed家族通用配置:串口控制台、FIT镜像支持、U-Boot provider声明、WKS文件。 ast2600.inc提供AST2600专用配置:CPU tuning、DEFAULTTUNE。 ast2600.conf提供AST2600 EVB完整机器配置:内核DTB、U-Boot defconfig、SPL、flash布局、initramfs格式。

meta-ubmc层

ummc.conf:定义UMMC单板(eMMC启动),设置UBOOT_MACHINE=ast2600_openbmc_spl_emmc_defconfig,配置SDK_POST_INSTALL_COMMAND修复工具链pkg-config路径,配置共享sstate和DL_DIR路径。 umtd.conf:定义UMTD单板(SPI Flash启动),设置UBOOT_MACHINE=ast2600_openbmc_spl_defconfig。

recipes-bsp/u-boot/:通过bbappend提供UMMC/UMTD的U-Boot配置碎片、环境变量文件、fw_env配置。 recipes-core/images/:openeuler-image-obmc.bbappend,移除webui-vue,配置EXTRA_USERS_PARAMS。 recipes-core/packagegroups/:packagegroup-ubmc-base.bb定义通用运行时依赖包组。 recipes-kernel/linux/:linux-openeuler.bbappend提供内核补丁(PECI、netfilter、MTD分区等)。 recipes-ubmc/initrdscripts/:ubmc-mmc-init.sh(eMMC版)和ubmc-mtd-init.sh(MTD版)initramfs脚本。

setup_oee.sh

阶段功能关键操作
参数解析解析命令行参数和环境变量-user/-pwd/-init/-board
用户创建创建/更新编译用户useradd + chpasswd + sudoers
系统依赖安装必要软件包apt install git python3 docker.io
Docker配置添加用户到docker组usermod -aG docker
oebuild安装安装oebuild工具pip3 install oebuild
工作区初始化创建oebuild工作区oebuild init + update
源码拉取克隆yocto_soc仓git clone
平台传播复制平台YAML和manifestcp platform/* + cat manifest.yaml
编译bitbake三阶段编译openeuler-image-obmc + u-boot + populate_sdk
SDK打包收集产物并打包cp + truncate + dd + mkfs.ext4 + zip

社区流水线集成

社区流水线脚本调用setup_oee.sh完成构建,构建完成后自动将产物oee_sdk_<时间戳>.zip上传到repo仓的指定位置,供社区开发者下载使用。流水线通过环境变量PRODUCT_NAME控制目标单板类型。

3.1.2 功能详细设计

见第 2 节 功能设计

3.1.3 开发者测试

3.1.3.1 单元测试

测试项输入预期结果
UMMC完整构建sudo ./setup_oee.shoee_sdk.zip产物完整
UMTD构建sudo ./setup_oee.sh -board umtdSDK为MTD版本
自定义参数sudo ./setup_oee.sh -user myuser -pwd mypass -init myws -board ummc以指定用户/工作区构建成功
重复执行第一次构建后再次执行用户已存在,更新密码后继续构建
参数缺失sudo ./setup_oee.sh -user ''报错退出

3.1.3.2 集成测试

测试场景配置预期结果
UMMC平台完整构建-board ummcoee_sdk.zip中包含u-boot-spl.bin、u-boot.bin、u-boot-env.bin、fitImage.img、oee_rootfs.tar.gz、工具链.sh
UMTD平台完整构建-board umtd同上,但U-Boot为SPI Flash版本
SDK产物验证-board ummcu-boot-env.img为2M,包含双副本
fitImage.img制作构建完成后fitImage.img为32M ext4格式,包含fitImage文件